home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 April: Mac OS SDK / Dev.CD Apr 00 SDK1.toast / Development Kits / Mac OS / Apple Remote Access API / ARA Security API 1.0 / Empty Shell / SecurityShell.c
Encoding:
Text File  |  1993-11-04  |  12.3 KB  |  409 lines  |  [TEXT/MPS ]
  1. //234567890123456789012345678901234567890123456789012345678901234567890123456789
  2. //===========================================================================
  3. //    File:    SecurityShell.c
  4. //
  5. //    This file contains a shell for add-on security modules for Apple
  6. //    Remote Access.  This code can be duplicated to write an add-on
  7. //    security code module.
  8. //
  9. //    Copyright © 1992, 1993 Apple Computer Inc.
  10. //    All rights reserved
  11. //
  12. //    Author:  Farzad Sarabi
  13. //
  14. //    Modification history:
  15. //
  16. //    5/10/1993    Farzad        A little cleanup, and added a completion routine.
  17. //                            Some more comments
  18. //    10/6/1992    Farzad        Created
  19. //===========================================================================
  20.  
  21.  
  22.  
  23. #include    "SecurityInterface.h"
  24.  
  25.  
  26. // #define SecurityShellVersion 0x0090
  27.  
  28.  
  29. //===========================================================================
  30. //    Example of Your Code
  31. //===========================================================================
  32.  
  33. // function prototypes
  34. static long        DoMyStartup( SecurityReference    MyReference,
  35.                              long                LongParam );
  36. static long        DoMyShutdown( SecurityReference        MyReference,
  37.                               long                    LongParam );
  38. static long        DoMyBegin( SecurityReference    MyReference,
  39.                            long                    LongParam );
  40. static long        DoMyEnd( SecurityReference    MyReference,
  41.                          long                LongParam );
  42. static long        DoMyDataHandler( SecurityReference    MyReference,
  43.                                  long                LongParam );
  44. static long        DoMyAbortHandler( SecurityReference        MyReference,
  45.                                   long                    LongParam );
  46. static long        DoMyTickleHandler( SecurityReference    MyReference,
  47.                                    long                    LongParam );
  48. pascal void        MyCompletionProc( SecurityReference        MyReference,
  49.                                   int                    ResultCode,
  50.                                   void                    * DataPtr,
  51.                                   int                    DataSize,
  52.                                   long                    CompletionParam );
  53.  
  54.  
  55.  
  56.  
  57. // the following is a shell for your code.  It shows how your entry routine
  58. // should be structured.  Empty supporting routines for the actions are
  59. // provided.
  60.  
  61.  
  62. // WARNING:
  63. //        Don't change the name of this routine.  We may change it in the
  64. //        future.  This is the routine ARA expects and calls.
  65.  
  66. pascal long        MySecurityProcEntry( SecurityActions        Action,
  67.                                      SecurityReference        MyReference,
  68.                                      long                    LongParam )
  69. //===========================================================================
  70. //    Description:    this is the entry point for the ??? security operation.
  71. //                    It is called by AppleTalk Remote Access to have this
  72. //                    security module perform the given operation.  It
  73. //                    dispatches to a variety of routines based on the
  74. //                    requested action.
  75. //
  76. //    Parameters:        Action                the action to be performed
  77. //                    MyReference            this is a unique value representing
  78. //                                        this instance of this code module.
  79. //                    DataPtr                the data for this action
  80. //                    DataSize            the size of data
  81. //
  82. //    Return Value:    long                result code, nonzero indicates an
  83. //                                        error.  Its value is one of the
  84. //                                        SecurityResultCodes.
  85. //
  86. //    Creation Date:
  87. //
  88. //    Modifications:
  89. //
  90. //===========================================================================
  91. {
  92.     switch ( Action )    {
  93.  
  94.       case    kSecurityStartup:
  95.         return DoMyStartup( MyReference, LongParam );
  96.  
  97.  
  98.       case    kSecurityShutdown:
  99.           return DoMyShutdown( MyReference, LongParam );
  100.  
  101.  
  102.       case    kSecurityBegin:
  103.           return DoMyBegin( MyReference, LongParam );
  104.  
  105.  
  106.       case    kSecurityEnd:
  107.           return DoMyEnd( MyReference, LongParam );
  108.  
  109.  
  110.       case    kSecurityDataAvailable:
  111.         return DoMyDataHandler( MyReference, LongParam );
  112.  
  113.  
  114.       case    kSecurityAbort:
  115.         return DoMyAbortHandler( MyReference, LongParam );
  116.  
  117.  
  118.       case    kSecurityTickleAction:
  119.           return DoMyTickleHandler( MyReference, LongParam );
  120.  
  121.     }
  122.  
  123.     return ( kSecurityUnsupportedAction );
  124. }
  125.  
  126.  
  127.  
  128.  
  129. static long        DoMyStartup( SecurityReference    MyReference,
  130.                              long                LongParam )
  131. //===========================================================================
  132. //    Description:    this routine handles the kSecurityStartup action.  You
  133. //                    should allocate any memory and setup the working
  134. //                    environment (e.g. A5 world) here.
  135. //
  136. //    Parameters:        MyReference        My unique reference
  137. //                    LongParam        additional information
  138. //
  139. //    Return Value:    long            result code, nonzero indicates error
  140. //
  141. //    Creation Date:
  142. //
  143. //    Modifications:
  144. //
  145. //===========================================================================
  146. {
  147. #pragma unused(MyReference)
  148. #pragma unused(LongParam)
  149.  
  150.     // this routine is called when the module has just been loaded.  You
  151.     // can preallocate any memory you need.  You are not yet starting any
  152.     // to do what this code resource is responsible for.
  153.  
  154.     // You can allocate and release memory in this routine.
  155.  
  156.     return ( kSecurityNoErr );
  157. }
  158.  
  159.  
  160.  
  161. static long        DoMyShutdown( SecurityReference        MyReference,
  162.                               long                    LongParam )
  163. //===========================================================================
  164. //    Description:    this routine handles the kSecurityShutdown action.  You
  165. //                    should release any memory allocated by the DoMyStartup
  166. //                    routine.
  167. //
  168. //    Parameters:        MyReference        My unique reference
  169. //                    LongParam        additional information
  170. //
  171. //    Return Value:    long            result code, nonzero indicates error
  172. //
  173. //    Creation Date:
  174. //
  175. //    Modifications:
  176. //
  177. //===========================================================================
  178. {
  179. #pragma unused(MyReference)
  180. #pragma unused(LongParam)
  181.  
  182.     // this is the last routine that is called before your code resource
  183.     // is released.  Just do any cleanup you need to perform.  ARA services
  184.     // are no longer available.
  185.  
  186.     // You can allocate and release memory in this routine.
  187.  
  188.     return ( kSecurityNoErr );
  189. }
  190.  
  191.  
  192.  
  193. static long        DoMyBegin( SecurityReference    MyReference,
  194.                            long                    LongParam )
  195. //===========================================================================
  196. //    Description:    this routine handles the kSecurityBeing action.  This
  197. //                    routine should start the operations the code resource
  198. //                    must do.  For example an authentication code resource
  199. //                    should start the authentication process.
  200. //
  201. //    Parameters:        MyReference        My unique reference
  202. //                    LongParam        additional information
  203. //
  204. //    Return Value:    long            result code, nonzero indicates error
  205. //
  206. //    Creation Date:
  207. //
  208. //    Modifications:
  209. //
  210. //===========================================================================
  211. {
  212. #pragma unused(MyReference)
  213. #pragma unused(LongParam)
  214.  
  215.     // This routine is called to actually start the code resource to do
  216.     // what it's responsible for.  E.g. an authentication code resource
  217.     // should start the authentication process.  A configuration module
  218.     // can start displaying a dialog etc.
  219.  
  220.     // You can allocate and release memory in this routine.
  221.  
  222.     return ( kSecurityNoErr );
  223. }
  224.  
  225.  
  226.  
  227. static long        DoMyEnd( SecurityReference    MyReference,
  228.                          long                LongParam )
  229. //===========================================================================
  230. //    Description:    this routine handles the kSecurityEnd action.  The action
  231. //                    is sent to signal the end of the operation the code
  232. //                    resource was created to do.
  233. //
  234. //    Parameters:        MyReference        My unique reference
  235. //                    LongParam        additional information
  236. //
  237. //    Return Value:    long            result code, nonzero indicates error
  238. //
  239. //    Creation Date:
  240. //
  241. //    Modifications:
  242. //
  243. //===========================================================================
  244. {
  245. #pragma unused(MyReference)
  246. #pragma unused(LongParam)
  247.  
  248.     // This routine is called when the code resource is finished.  It is
  249.     // called as a result of you calling ARAAllowUser, ARADontAllowUser,
  250.     // ARACompleteOperation, or after ARA aborts your code resource.
  251.     // You could for example cleanup any outstanding asynch calls to the
  252.     // Mac OS.  ARA services are no longer available.
  253.  
  254.     // You can allocate and release memory in this routine.
  255.  
  256.     return ( kSecurityNoErr );
  257. }
  258.  
  259.  
  260.  
  261. static long        DoMyDataHandler( SecurityReference    MyReference,
  262.                                  long                LongParam )
  263. //===========================================================================
  264. //    Description:    this routine handles the kSecurityDataAvailable action.
  265. //                    The action is sent when data has arrived for the code
  266. //                    resource.
  267. //
  268. //    Parameters:        MyReference        My unique reference
  269. //                    LongParam        additional information
  270. //
  271. //    Return Value:    long            result code, nonzero indicates error
  272. //
  273. //    Creation Date:
  274. //
  275. //    Modifications:
  276. //
  277. //===========================================================================
  278. {
  279. #pragma unused(MyReference)
  280. #pragma unused(LongParam)
  281.  
  282.     // This routine is not used in this release of the ARA Add-on Security.
  283.     // In future releases we may use this to indicate data being available
  284.     // for you.  ARA may in the future send events to a modeless dialog
  285.     // box using the DataAvailable message.
  286.  
  287.     // You can allocate and release memory in this routine.
  288.  
  289.     return ( kSecurityNoErr );
  290. }
  291.  
  292.  
  293.  
  294. static long        DoMyAbortHandler( SecurityReference        MyReference,
  295.                                   long                    LongParam )
  296. //===========================================================================
  297. //    Description:    this routine handles the kSecurityAbort action.  The
  298. //                    abort action is sent when the code resources operation
  299. //                    needs to be terminated abnormally.
  300. //
  301. //    Parameters:        MyReference        My unique reference
  302. //                    LongParam        additional information
  303. //
  304. //    Return Value:    long            result code, nonzero indicates error
  305. //
  306. //    Creation Date:
  307. //
  308. //    Modifications:
  309. //
  310. //===========================================================================
  311. {
  312. // you can remove the unused pragma for any of the parameters you use
  313. #pragma unused(MyReference)
  314. #pragma unused(LongParam)
  315.  
  316.     // This routine is called when the code resource is being aborted.
  317.     // You should not make any more calls to ARA services, and you should
  318.     // start your abort process.  You will receive the End and Shutdown
  319.     // actions a little while later.
  320.  
  321.     // You can allocate and release memory in this routine.
  322.  
  323.     return ( kSecurityNoErr );
  324. }
  325.  
  326.  
  327.  
  328. static long        DoMyTickleHandler( SecurityReference    MyReference,
  329.                                    long                    LongParam )
  330. //===========================================================================
  331. //    Description:    this routine handles the kSecurityTickle action.  ARA
  332. //                    sends this action periodically.  The action is also
  333. //                    generated as a result of a call to ARATickleMe routine.
  334. //                    
  335. //
  336. //    Parameters:        MyReference        My unique reference
  337. //                    LongParam        When ARA calls this value will be 0,
  338. //                                    otherwise it is the value passed to
  339. //                                    the ARATickleMe routine.
  340. //
  341. //    Return Value:    long            result code, nonzero indicates error
  342. //
  343. //    Creation Date:
  344. //
  345. //    Modifications:
  346. //
  347. //===========================================================================
  348. {
  349. // you can remove the unused pragma for any of the parameters you use
  350. #pragma unused(MyReference)
  351. #pragma unused(LongParam)
  352.  
  353.     // ARA calls this routine periodically.  You can also initiate a call
  354.     // to this routine by calling ARATickleMe.  When ARA calls this
  355.     // routine the LongParam value will be 0 (zero).  When it is called as
  356.     // a result of a call to ARATickleMe the LongParam will have the value
  357.     // you passed to ARATickleMe.
  358.  
  359.     // You can allocate and release memory in this routine.
  360.  
  361.     return ( kSecurityNoErr );
  362. }
  363.  
  364.  
  365.  
  366. pascal void        MyCompletionProc( SecurityReference        MyReference,
  367.                                   int                    ResultCode,
  368.                                   void                    * DataPtr,
  369.                                   int                    DataSize,
  370.                                   long                    CompletionParam )
  371. //===========================================================================
  372. //    Description:    this is an example of your a completion routine you can
  373. //                    use for calls to asynch ARA services.  You can use one
  374. //                    completion proc and distinguish the reason it was called
  375. //                    by the value passed in the CompletionParam.
  376. //                    
  377. //
  378. //    Parameters:        MyReference        your unique reference
  379. //                    ResultCode        result of the asynch ARA call you made
  380. //                    DataPtr            pointer to the data passed to the ARA
  381. //                                    proc
  382. //                    DataSize        actual size of the data
  383. //                    CompletionParam    additional information you provided 
  384. //                                    to the ARA service proc
  385. //
  386. //    Return Value:    none
  387. //
  388. //    Creation Date:
  389. //
  390. //    Modifications:
  391. //
  392. //===========================================================================
  393. {
  394. // you can remove the unused pragma for any of the parameters you use
  395. #pragma unused(MyReference)
  396. #pragma unused(ResultCode)
  397. #pragma unused(DataPtr)
  398. #pragma unused(DataSize)
  399. #pragma unused(CompletionParam)
  400.  
  401.     // WARNING:
  402.     //            Do not attempt to allocate or release any memory in this
  403.     //            routine.  Also don't call any Mac Toolbaox/OS routines 
  404.     //            that allocate or release memory.  If you need to do this,
  405.     //            you should call ARATickleMe with a state indicator, and
  406.     //            allow your DoMyTickle routine to handle it.
  407.  
  408.     return;
  409. }